feat(compliance): add status transition guards with pre-flight reads - #171

Summary

Closes #27

The compliance lifecycle already rejected illegal status changes, but it could not explain a rejection ahead of time. A client had three bad options: re-implement the rules (two copies of a compliance-critical rule set, free to drift), submit and translate the revert (burns a transaction, and a bare Unauthorized cannot distinguish "you need a role" from "this address is frozen and only the admin can lift it"), or read is_compliance_transition_allowed (matrix-only — it ignores the caller, the pause, and the admin-only exit from Blocked, so true did not mean the call would succeed).

This PR adds a guard layer that closes the gap by making one evaluation serve both purposes: the pre-flight reads and every state-changing compliance call reach their verdict through the same function. A pre-flight verdict cannot disagree with enforcement, because there is nothing to disagree with.

What was added

src/compliance_guards.rs — the ordered guard chain, evaluated by a function that never panics and never writes:

Two ordering choices are deliberate and documented: pause before authority (a paused contract reports the pause to everyone and never leaks whether the caller would otherwise have qualified) and authority before the matrix (an unauthorized caller learns nothing about edges for an address they may not touch).

BlockedRequiresAdmin is separated from CallerUnauthorized. Both map to Unauthorized (3000) on-chain, but the remediation differs — "escalate to the admin" vs. "request a role". A client that collapses them tells a properly-credentialed officer to ask for a permission they already hold.

Three pure reads — check_compliance_transition, get_compliance_transition_guard, check_compliance_batch. No authorization, no writes, no events, callable while paused. ComplianceTransitionCheck carries the resolved current_status (so a client cannot race a separate status read against it) and a pre-resolved error_code.

compliance.rs refactored to use the same evaluation. Backwards compatibility is exact: availability/authorization failures still panic, rule violations still return typed Err, and the tolerant legacy wrappers (whitelist_user / revoke_whitelist) keep their idempotent no-op behaviour while still being unable to lift a freeze.

Notes for the reviewer

• Two pre-existing failures on main are fixed here so the suite is green. They are unrelated to this issue and I kept them minimal: (1) fixtures/sdk/01-compliance.json had drifted and was regenerated with make update-fixtures; (2) fixture_errors asserted AssetNotActive (6000) and AssetLifecyclePaused (6001) for mint attempts that the contract already reports as 7002 / 7000 — docs/error-codes.md already documents 6000 as "Reserved. Superseded by 7000–7002; no longer emitted", so the expectations were stale, not the contract. cargo fmt also normalized src/config.rs / src/config_test.rs, which were unformatted on main. The same three fixes appear in the PR for Implement issuer role separation #28; whichever merges second can drop them.
• No behaviour change to any existing entrypoint — all 180 pre-existing tests pass untouched.

Test Evidence

cargo test                                     197 passed; 0 failed   (180 pre-existing + 17 new)
cargo test --test sdk_fixtures                  10 passed; 0 failed
cargo fmt --all -- --check                      clean
cargo build --target wasm32v1-none --release    ok

The load-bearing tests assert agreement rather than a hardcoded expectation, so they fail if the read path and the write path ever diverge: all 5 × 5 source/target edges are walked three times (officer, admin, unauthorized caller), each on a fresh deployment, comparing the pre-flight verdict against the real submission's outcome, error code, and resulting status.

Completion Table

Contributor Self-Assessment

• Scope Confirmation: Changes match issue scope. The three pre-existing repo fixes are called out above.
• Test Evidence: All tests pass locally (207 total across both suites).
• CI Status: fmt-check, clippy (no new warnings from the new module), test, and the wasm release build all pass locally.
• Known Limitations: A guard verdict is point-in-time and not a reservation; the guard does not evaluate require_auth. Both are documented as explicit assumptions in docs/compliance-transition-guards.md.
• Acceptance Criteria: Every criterion verified in the table above.

Protocol-level compliance controls only. Nothing here is legal or financial advice — see docs/legal-boundary-disclaimer.md.